Ficedula DirectMusic, a input plugin for Winamp
ficedula@lycos.co.uk

Check out the Final Fantasy Soundfont Project at http://ffsf.cjb.net
Thanks to the Jedi Project for the DirectX headers, stnd.de for the Winamp headers,
Sillex for example DirectMusic code.


This plugin lets you play MIDI and Segment files (.MID, .SGT) through DirectMusic. It can
use any DirectMusic device (e.g. MS Softsynth) and autoloads the associated DLS files.
The MS Softsynth is probably the only device supporting DLS on most systems. Alternatively
if a device supports Soundfonts (AWE32/64, SBLive!) it can load the associated soundfont
bank automatically and play through that.


Important
~~~~~~~~~
Some SGT files must have the downloadable sound (DLS) file loaded to play, even if you
are playing them through a soundcard that doesn't support DLS (FF8 for example).

If the SGT file is in the same directory as the DLS the plugin should find the DLS.
If Winamp crashes when you try to play some SGT's though, this is probably the reason
and you need to set up a profile as described below. Also if a DLS is automatically
loaded the instruments can sound wrong. To fix this create a profile. If you use
soundfonts you will need a profile anyway as these can't be loaded automatically.


Profiles
~~~~~~~~
The default setting plays all files through the MS Softsynth using the default DLS bank.
While this will work for many files some games may need to have their own setup to make
the music sound correct (or to prevent a crash!).

Create a "Profile" for each set of music. A profile is a music device (i.e. which driver
to use) with an associated DLS/soundfont file to be loaded. For example Final Fantasy VIII
needs to have its own custom DLS/soundfont loaded, so it may need its own profile.
Go to the "Manage profiles" page of the config dialog. Above the profiles list, click
the new profile icon. Select new profile and fill in the details.

 - "Name" is just a way for you to keep track of the profiles.
 - "Device" is which driver to use to playback, eg. MS Softsynth, SB Live!, etc.
 - "Soundfont" is only available if you select a driver which supports soundfont banks
   (Creative cards, usually). Choose a soundfont to load when the profile is active.
 - "DLS" is always available. If the files use a custom DLS file select it here. You may
   need to do this even if you play through a soundfont device that doesn't support DLS.
 - "Reverb" and "Chorus" are special effects, normally only available with DLS devices.
 - "Bank number" is the bank to load soundfonts into. 0=Synth bank (usually best option).

Once you have filled in the details click "Save changes".

Go to the "Assign profiles" page. This is where you control which files use which profile.
Click "New item" to add a new assignation. Select it in the list and change the "profile"
option to your newly created one and fill in the filespec for this profile (use wildcards).
E.g. "C:\MUSIC\*" means all files in C:\MUSIC and its subfolders, "*\FF8\*" means all files
where the full path contains a folder named "FF8". You can also change the name of the
assignation and how many times it loops. In the playlist choose "File Info" from the popup
menu (Alt-F3) to see which profile a SGT or MID file would play with.

Note that items at the top of the list are checked first! You can still keep an item that
applies to "*.*" (all files) at the bottom of the list, this is only used if a music file
fails to match all the items above it.


Options
~~~~~~~
Release soundfont memory: Only useful with soundfont cards. If a soundfont bank was loaded
to play a file the memory is cleared afterwards unless the next file needs it. Useful for
SBLive! cards or if you want to leave Winamp open and use other Soundfont programs.

Intelligent soundfont loading: When this is turned on the plugin tries to load only the parts
of a soundfont files that are actually used by the file being played. This often saves a lot
of memory. The only disadvantage is that loading time is slower. Currently it only works for
SGT files. Note that some files 'switch' instruments part way through which means the plugin
probably hasn't got the new instrument loaded. To solve this either don't use partial loading
or create a patch file. This should be in the same folder as the original file but with the
extension .PAT, and is plain text. It contains lines listing the bank/instrument numbers to
load in addition to those detected, eg:

0,0 to load bank 0, instrument 0 (piano)
1,23 to load bank 1, instrument 23
2 to load percussion instrument 2 (hence no bank number)

or, to load an instrument into a different location in memory than it's place in the file
0,0->1,0	load bank0 instr0 into location bank1 instr1 in memory.
2->3		load percussion2 into location percussion3

Titles: Midi and segment files don't generally contains titles. This lets you choose files
that match a filename to a title to be displayed in the Winamp playlist. The files must
contain plain text like this:

BAT.MID=Battle theme
END.MID=Ending theme
...

Cache lengths: The lenght of MIDI/SGT files can't be detected easily as they can loop, or
the tempo may change part way through. The only way to get the exact length is to play the
file. With this option enabled the plugin measures the playtime and stores the value to the
Winamp playlist.

Extra information: Displays more information from SF2 files (eg. instrument sizes and names).


Known bugs
~~~~~~~~~~
 - The config and about windows aren't modal, you can go back to Winamp without closing them.
 - Sometimes the plugin get stuck on a song and refuses to go to the next file. This only
   happens if Winamp is in the background. Just restore Winamp to continue, then you can
   minimise it again.
 - When the plugin exits it tries to restore any soundfont memory to its initial state.
   This should always work unless one of the following has happened:
   - Winamp crashed.
   - Another program modified the oundfont memory.
   - Custom instruments (e.g. from WAV files) were loaded.
 - Also when loading soundfonts you will probably always need to use bank 0 (synth) even
   if the soundfont was meant to be loaded into another bank (e.g. Final Fantasy 7 music).
   The soundfonts by Square are normally loaded into bank 1 but DirectMusic doesn't use
   any bank but 0 unless the actual music files (SGT/MID) are modified to cope.


History
~~~~~~~
v1.10
 - Added support for .MIX files. These are just plain text files containing a list
   of segments to play at the same time.
 - Added partial loading for soundfonts. Loads only instruments being used.
 - A few visual fixes.
 - File info box gives more information on the files including size of instruments
   and their names. (SF2 only)
 - Fixed "Access Violation" crashes (again).
 - Got rid of profile/assigns, now combined into one setting.

v1.01
 - Fixed instruments sounding incorrect. This fix only works if the DLS bank is loaded
   through a profile, not if it is automatically loaded.
 - Fixed "Access Violation" crashes. Caused by some parts of the program trying to play
   the file even after it was stopped.
 - Moved "Loop" option to a per-assign setting rather than a setting for every file.
 - Removed "Response time" setting, now always is set to 450ms.
 - Fixed the registry reader. If a registry setting didn't exist it was created with
   defaults, if the values existed but were corrupt it got confused.
 - Most exceptions are now handled silently (i.e. error messages don't pop up as often).
 - Volume/Pan controls now work! (Directmusic soundcards only, not older legacy devices)
 - Fixed wildcard matching. E.g. now you can use "*.MID" if you don't care which folder
   the file is in.
 - Added caching. Can measure the length of a file and store it for later use.
   Note that if you move a file to another location measures need to be reacquired.
